 
  Help for MyMenu
 

This program is Freeware. (C) 1996 Richard Atterer
V0.90, 29th September 1996

Contents:
1.     Introduction
1.1.   Legal things
1.2.   Short description
1.3.   So when is it useful?
1.4.   Usage

2.     The menu file
2.1.   Introduction
2.2.   Syntax
2.2.1. Commands before menu/menu entry definitions
2.2.2. Menu definitions
2.2.3. Menu entry definitions
2.2.4. *commands following entry definitions
2.2.5. Modifiers
2.3.   Useful *commands

3.     Tips & Tricks

4.     Known problems

5.     The TypeName application

____________________________________________________________________________


1.     Introduction
===================

1.1.   Legal things

This program is Freeware. (C) 1996 Richard Atterer
No profit must be made when this program is spread  any charges must not exceed the costs of spreading (eg discs, postage). To spread this program as an extra together with commercial software, with a magazine or the like, the prior written consent of the author is necessary.
You must always pass on all files of the program.
Using the program is at your own risk! The author cannot be made responsible for any damage resulting from the use of the program, even if caused by errors in the program or the documentation. No warranty, express or implied, is made about the suitability of the program for any purpose.


1.2.   Short description

MyMenu is a program which allows you to create a menu system of your own in a comfortable and easy way. Selecting a menu entry executes one or more *commands (which, for example, can open directories or start applications). Additionally, you can define any key combination you like (even including mouse buttons!) as hotkeys. When the keys are pressed, the appropriate menu is opened or the *commands of the menu entry are executed.
Even if you have no idea as to how to use *commands (pronounced star commands)  dont worry, the most important ones are described later!

Because MyMenu must be loaded into memory all the time in order to intercept the hotkeys, special care has been taken to make sure that it needs as little memory as possible: If the menu is only loaded from disc once it is needed (it can also be stored in memory permanently), the program just takes up a little more than 2.6 kBytes  regardless of the size of the menu.


1.3.   So when is it useful?

 when starting applications  eg just press Alt Print to load your printer driver, or make one of your 50 favourite programs appear on the icon bar with two mouse clicks, but without having to wait for the 49 others in the same directory to be booted first
 if you have a CD ROM drive  you can include important directories/programs on your CDs in your menu, thus avoiding that you constantly have to open lots of directories to reach them. Of course, the same also applies to hard discs.
 for large numbers of floppy discs (if you dont have a hard disc)
 for doing other things which you usually have to do again and again  eg if you want to load your word processor, but first want to change screen mode, add more fonts to those known to the system, make the font cache larger, start !Chars etc. etc.


1.4.   Usage

MyMenu needs RISC OS 3.00 or later. (It has been tested under RISC OS 3.11, 3.6 and 3.7/StrongARM)
When the program is started by double-clicking, nothing seems to happen since MyMenu does not provide an icon on the icon bar. Naturally, because of this it cannot be quitted as usual via the icon bar menu. Instead, this must be done in the task manager window.
Under RISC OS 3.11, MyMenu survives soft resets (ie Shift Break or reset button without further keys down). Unfortunately, there are no soft resets any longer under RISC OS 3.5 and later... [SORRY, THIS DOES NOT WORK PROPERLY AT PRESENT]

At first, an example menu is provided which you can of course alter (indeed I expect you to!)  however if you pass MyMenu on to other people, always include the original menu. The hotkeys defined in the example allow to run the ROM applications by pressing Alt together with the first letter of the respective application, and the menu is opened if you click MENU when the pointer is at the left screen border.



2.     The menu file
====================

2.1.   Introduction

The text file Menu inside the directory !MyMenu.Menu describes what your menu will look like. In the same directory there is also a file called MenuScan in which the information of the menu file is stored. It is created automatically by MyMenu to ensure that loading the menu is fast. This is done because interpreting the menu file itself may sometimes take a second or longer with (very) large menus, which can become annoying. Whats more, by first saving the menu data in a format which MyMenu can use directly it is avoided that the part of the program which does the interpreting needs to be loaded permanently; this saves nearly 5 kBytes. However, it also means that any changes made to the menu file are only brought into effect when MyMenu is restarted. To do this, just double-click again on !MyMenu, or alternatively on the file RescanMenu inside the directory !MyMenu.Menu.
(By the way: When started, the program finds out whether or not MenuScan needs to be updated by checking if it has the same date stamp as Menu.)


2.2.   Syntax

During interpretation, the menu file Menu is read in line by line. Any empty lines and lines whose first character is | (ie comments) are ignored. In every line there must only be one command. Spaces before and after commands (except lines with *commands) are not allowed.


2.2.1. Commands before menu/menu entry definitions
--------------------------------------------------
Before the menu and menu entry definitions begin, other commands may appear in the file:

Special:*
This line, which must always appear in the file, defines a character ( * in this case) which has a special meaning for the menu definitions following later in the file. Normally, it should not be necessary to use a different character than * but you may want to do that if your menu doesnt meet the following restrictions:
 The special character must not be part of a menu name
 It must not be the first character of a menu entry.
 No *commands must begin with the special character.

LoadOnDemand
If this command is not present, the file MenuScan containing the menu is loaded when MyMenu is started and the menu remains in memory all the time. If LoadOnDemand is present, MenuScan will only be loaded on demand, ie when a menu is to be displayed or when the *commands for a particular hotkey are to be executed. Once the menu has disappeared again or the last *command has been executed, the menu data is forgotten again,  so it must be reloaded again and again. For this reason, LoadOnDemand should not be used by people with no hard disc  all others can use it if they think their menu uses up too much memory. (The amount of memory needed is the file size of MenuScan.)

BufferAll
If present, this line makes the program behave as if every single of the menu entries in the file had a B-Modifier  it doesnt matter if there really is one or not. The B-Modifier is described later in this file.
I strongly recommend using BufferAll when LoadOnDemand is used  otherwise, two file accesses are necessary in order to execute *commands.


After the 1 to 3 commands described above, only menu and menu entry definitions may appear in the file.
Note: The following descriptions assume that the special character has been defined as * . If this is not the case in your file, you must of course use the character you chose instead of *


2.2.2. Menu definitions
-----------------------
Menus are defined with:
**Menu name*

You can also use one command to create a menu and at the same time a submenu of that menu:
**Menu name*Submenu name*
or
**Menu name*Submenu name*Sub-submenu name*
and so on. ** must stand before the first menu name, * after every menu name.

It is possible to refer to menus which already exist. The lines:
**MyMenu*Gfx & Sound*Graphics*
**MyMenu*Gfx & Sound*Sound*
create four menus: MyMenu, Gfx & Sound and, as submenus of Gfx & Sound, the two menus Graphics and Sound.

Basically, this way of defining menus means that each menu is defined using its path inside the whole menu structure, similar to the pathnames used to access files. 


2.2.3. Menu entry definitions
-----------------------------
Menu entries are defined with
*name of menu entry*
<followed by one or more lines of *commands>

The name of the entry may contain the character * anywhere except at the beginning. *File $.M** is possible (youll get the entry File $.M*) whereas **Info is not  this would be interpreted as a menu definition, not as an entry called *Info.
The end of the lines of *commands is recognized by the fact that the first character of the following line is * (or, of course, that the end of the file has been reached).

In contrast to menu definitions, definitions of menu entries dont require the full pathname to be supplied. Instead, the entry is included in the menu given in the last menu definition. This principle is best demonstrated with an example:

These lines:                    ...will create this structure:
**MyMenu*                           
*Say hello*                         
Echo Hello                          ++
**MyMenu*Apps*                      | MyMenu    |+ 
*Chars*                             +| Apps      | 
ChangeDynamicArea -fontsize 128k    | Say hello |+
/Resources:$.Apps.!Chars            | Apps    =>| Chars     | 
*ChangeFSI*                         | Mode 31   | ChangeFSI | 
/<ChangeFSI$Dir>                    +++
**MyMenu*                           
*Mode 31*
WimpMode 31

Note that the order in which the entries appear in the menu depends on which one comes first in the menu file. This also applies to entries created during menu definitions: In our example, the submenu Apps is only defined after Say hello has been included in the main menu and consequently the menu entry which opens the Apps submenu is displayed below Say hello.
By the way: It doesnt matter at all how often you switch over between different menus (in the example first MyMenu, next Apps and then MyMenu again)  this has no influence on the size of MenuScan and so doesnt result in more memory being needed.


2.2.4. *commands following entry definitions
--------------------------------------------
The example also makes clear what an entrys *commands may look like. Below every entry at least one *command line must follow. Comments and empty lines, which can even appear between individual lines of *commands, are already ignored during interpretation, so they dont count.

A few more notes for advanced people:
 The *commands are not executed like lines of an Obey file but like lines of a Desktop file  not with OS_CLI, but with Wimp_StartTask. The reason for this is that otherwise it would be very easy to crash the computer, eg if you try to start a file with Run (it would be loaded into the application space of the currently active task!). Furthermore, to simulate an Obey file you cant just pass the commands to OS_CLI, instead a command to be provided by MyMenu would have to be passed to Wimp_StartTask and the individual commands would have to be executed from within its code (you would also have to take care that Obey stops the execution  even if it is part of an If...Then line). Whats more, MyMenus own Wimp slot would not be there so if the menu were only loaded on demand, it would have to be loaded into the RMA (at least under RISC OS 3.11, where there are no dynamic areas) and fragment it. All in all, this is just too much effort...
 The differences between Obey and Desktop files make certain commands unusable, such as WimpSlot (as soon as WimpSlot has been executed, the slot is re-set to the size of next), or anything which loads an application with one command and starts it with the next command  these two things must happen in one command. All commands which dont affect the current slot will work as expected.
 The unusual way Wimp_StartTask handles errors is responsible for the fact that execution of the *commands is continued even after an error. (I can do nothing about that because any error messages are printed out immediately and are not passed back to MyMenu.)

The *commands most useful for MyMenu are described later in this file.

When creating the *commands of a menu file, you would normally have to type in lots and lots of file paths. As this can take up a considerable amount of time (not to mention the typing errors you inevitably make), I have written a small application called TypeName which does the job for you. Its use is also described later.


2.2.5. Modifiers
----------------
The description of the commands for menu and menu entry definitions is still incomplete: After the last * of those lines, one or more extra commands may be appended, eg like this:

**MyMenu*Menu*K5E71;L

Two modifiers have been appended to this line, seperated by the ; character: A K modifier (followed by a parameter) and an L modifier. Altogether, there are four different modifiers (B, K, L and M).

B modifier (ie buffer)
This modifier is possible at the end of menu definitions as well as entry definitions, though if it appears at the end of a menu definition this has just the same effect as if it had been applied to each individual entry after this menu definition up to the next one  it will be ignored whether the entries actually have a B modifier. (This saves the work of appending the B to each entry.)
The B modifier influences the way the *commands of the respective entry (or of all entries of that menu) are treated. If it is present, the *commands are included in the file MenuScan (and so will be loaded whenever the menu is loaded), if it is not present, MenuScan will only contain information about where to find the *commands in the menu file Menu. Consequently, the effect of the modifier is to increase the size of MenuScan (or decrease it, if it isnt present)  when it is used on all entries, the file will typically be two to three times as large. However, if this modifier is not used, an additional access to the Menu file is necessary before the *commands can be executed (and this is not recommendable if Menu has to be loaded from floppy disc or over a network). In the end, things depend mainly on whether LoadOnDemand is used:
 If it is used, you should issue BufferAll at the beginning of the file to make sure all *commands are included in MenuScan. Of course, this results in the file being quite large, but as the data isnt stored in memory permantently anyway, that doesnt matter.
 If LoadOnDemand is not used, its up to you to decide whether you want few or no file accesses but less free memory (B modifier present), or if you prefer to be able to open the menu immediately with just little memory used but with a file access necessary once you click on a menu entry (B modifier not present). As always, a compromise will do best...

Well, finally you might begin to wonder what kind of memory usage fanatic I am  because actually those 20 kBytes or so used by MyMenu even with a bigger menu arent that much, are they? The reason is: I just dont like those utilities and programs which you include in your boot sequence and each of which needs its workspace until all of a sudden it adds up to half a Megabyte or more...

K modifier (ie key)
This modifier is used to define the hotkeys. It is the only one to be followed by a parameter which consists of 2, 4, 6 or 8 characters  two characters for each hotkey. Usually you wont need to worry about the code of those two chars (a hexadecimal number). Just use the TypeName application: Click on K in the right upper corner and press the desired key combination. Once the keys are released, TypeName types the right K modifier into your text editor.
Internally, mouse buttons are treated in the same way as keys, so hotkey combinations such as Alt MENU to open a menu are perfectly possible.
If the K modifier is appended to a menu definition, pressing the keys will open that menu. For a menu entry, the *commands of the entry will be executed.

L modifier (ie line)
The L modifier creates a dotted line below the menu entry to which it has been appended, or, in the case of menu definitions, below the menu entry leading to this menu. For example:
**MyMenu*Menu*
This will create a dotted line below the entry Menu in the MyMenu menu.
The program will ignore any L modifiers which place dotted lines below the last entry of a menu.

M modifier (ie MENU)
The last of the four possible modifiers does the same thing as the K modifier except that it will not open the menu when some keys are pressed but when MENU is clicked while the pointer is at the left screen border. This is really convenient because you neednt press any additional keys while you click the mouse button. (This idea has of course been stolen from StrongED  being a Zap user I just found it too good, so I included it in MyMenu.)


2.3.   Useful *commands

Some *commands are very useful for a menu file, so theyll be described briefly here. By the way: All *commands are listed and described in the User Guide (or in a file on your hard disc)!
In the text below, <pathname> stands for the full pathname of a file or application, for example Resources:$.Apps.!Chars (typed in without quotes).

There are several ways to start applications. Usually, all programs should be started correctly with this command:
Run <pathname>
This can be abbreviated to:
/<pathname>
In case this doesnt work, try the following:
Filer_Run <pathname>
If now there are still problems (eg no icon on the icon bar), enter these two lines below your entry definition:
Filer_Boot <pathname>
Filer_Run <pathname>

If you want to access files or programs inside ArcFS archives, you must ensure that ArcFS is loaded before trying to do so, because if it isnt youll just get an error. The following line will load ArcFS in case it isnt already loaded:
RMEnsure ArcFS 0 /<ArcFS$Dir>
However, this only works if ArcFS has already been seen, ie a directory containing it has been opened. If this is not convenient for you because it means youll have to open the directory again and again (I recommend having ArcFS booted automatically after every reset though), you can change the last part of the line, eg like this:
RMEnsure ArcFS 0 /ADFS::MyDisc.$.!ArcFS

Because some commands (especially the above one) appear many times in a menu file, MyMenu has had the feature added to detect those *command lines and replace subsequent matches with short references to the first appearance of the command. This can save a lot of memory. To match, the lines must be EXACTLY the same, though, ie same case of letters and no additional leading or trailing spaces. (Of course, this only applies to *commands which are buffered in MenuScan.)


Filer_Boot <pathname>
This command boots the specified application (just as if a directory containing it had been opened), so that, for example, it will be loaded if a file it recognizes is double-clicked.

Filer_Run <pathname>
Filer_Run can be used not only for starting applications but also for starting files  the effect of this command is the same as when a file icon is double-clicked, eg if the file is a text file, it will be loaded into your text editor.

Filer_OpenDir <pathname>
This command is used to open directories on the desktop.



3.     Tips & Tricks
====================

 It is possible that menu entry definitions appear in the menu file even before any menus have been defined. These entries will then not be listed in any menu, which might be useful if you want to define a hotkey, but dont need the associated menu entry.
 You can of course define several totally independent menu trees  the first menu name after ** neednt always be the same!
 When defining hotkeys, keep in mind that the program distinguishes between the left and right Shift, Alt and Ctrl keys and also between the normal numerical keys and those on the numerical keyboard.
 A menu or menu entry can have more than one hotkey, so you can do things such as defining Alt Z with the left as well as the right Alt key.
 If you want to execute small programs or Obey files of your own with *commands, you can copy them into the directory !MyMenu.Menu which can be accessed with the system variable MyMenu$M.
 Menu entries of twelve or less characters save space.
 In case a submenu you define doesnt appear in you menu, check if you have spelled the name of your main menu right.
 If you use LoadOnDemand and your menu is loaded from a hard disc, you may notice that the drives LED isnt always on when it is loaded. This is because ADFS uses a buffer that is normally bigger than MenuScan, so the file actually neednt be re-loaded every time. However, the buffers contents will be forgotten again (though maybe only partially) once a different file is loaded.
 If an error message like Error when reading XXX  directory XXX not found (of course with a directory name instead of XXX) is displayed, the reason is usually that a file inside an archive should have been loaded, but ArcFS was not present.



4.     Known problems
=====================

 MyMenu cannot be used together with the CDKeys module. However, this is the fault of CDKeys. (It doesnt pass on the key up/down event when a keypress it recognizes occurs.) Also experienced problems with Reversi by Alex Hopkins (God knows why).
 Usually, when hotkeys are pressed the keypress is intercepted to avoid that other programs react to it, too. Unfortunately, this is not possible when the cursor is currently in a writable icon.
 I did not have the opportunity to test this program on a RiscPC with any other than the standard keyboard. Nevertheless, things ought to work fine with other keyboards, too. (The only restriction: The codes sent by the keyboard must only be eight bits wide!)
 As has already been mentioned, execution of *commands will continue after an error  I can do nothing about that.
 An entrys *commands must not be used to quit or restart MyMenu itself  this will crash the machine!!!
 MyMenu does recognize hotkeys of up to four keys pressed simultaneously, but key combinations of three or four keys will only work if they include Shift, Alt and/or Ctrl  once more than two alphanumeric keys are down, further key presses are ignored (this is due to limitations of the keyboard) ...sorry for all those acrobats among you!
 MyMenu itself does not impose any restrictions on the maximum number of submenu levels. However, the operating system does not allow more than seven submenu levels, ie there must never be more than eight menu-windows on the screen. This should be more than enough though.



5.     The TypeName application
=================================

TypeName is a small application which eases the creation of a menu file by typing in file and directory names, K modifiers and other frequently needed strings for you.

When the program is started, a window is opened. There is no icon bar icon  once you close the window, TypeName will quit.

Dragging a file or directory to the window results in its full path name being typed, just as if you had typed it on the keyboard. For this to be useful, the input focus must of course be in a text editor or something similar when you drag the file. By turning on or off the option Press Return after file name you can influence whether the name will be followed by a newline.
Additionally, you can make the program type any string you have previously entered in one of the three writable icons by clicking on the button right of the respective icon. To allow newlines to be entered, all  characters (code 255) encountered in the string are replaced with newlines. (Bad luck if you want this character to appear in your editor...)
To have K modifiers typed, click on K in the right upper corner and press and release the desired keys.

An error message will be given if you try to have something typed and the input focus is currently in TypeNames own window.

[ Last minute note: To my shame, I have just discovered that Zap, StrongED and Edit will type files names when you shift-drag the file icon to their window  SILLY ME! ]



Have fun with this program!
Richard Atterer, November 1996
